ARCHITECTURE.md：代码库导航地图（整理版）

原始资料：matklad《ARCHITECTURE.md》 原始笔记：ARCHITECTURE 相关笔记：[OpenAI Harness：Agent-first 工程方法](/en/original-notes/self_study_notes/harness/OpenAI Harness/整理版/OpenAI Harness（整理版）)、[rust-analyzer 架构文档示例](/en/original-notes/self_study_notes/harness/OpenAI Harness/整理版/architecture_example（整理版）)、[本目录索引](/en/original-notes/self_study_notes/harness/OpenAI Harness/整理版/索引) 整理说明：本版本结合原始笔记与原始教程重排、补全和翻译。

内容简要概括

ARCHITECTURE.md 是与 README、CONTRIBUTING 并列的高层导航文档，用来缩短新贡献者和 Agent 定位“该改哪里、当前模块做什么”的时间。它应保持短小、描述不易变化的结构事实，并以鸟瞰图和 codemap 为核心，而不是复述实现细节。重要模块以名称而非易失的行号链接引用，长期约束以 architectural invariants 明确表达。

ARCHITECTURE.md、codemap、bird's-eye view、architectural invariants、API Boundary、dependency rules、symbol search、模块边界、稳定文档、Agent legibility

1. 文档目标与边界

大型代码库最昂贵的常常不是写补丁，而是定位改动位置。ARCHITECTURE.md 的任务是建立一张“物理架构”的心智地图，回答两个问题：

“实现 X 的地方在哪里？”
“我正在阅读的模块负责什么，它与谁协作？”

它不是代码同步副本。文件越短，越不容易因日常实现变化失效；只记录数月后仍可能成立的模块关系、入口、边界和依赖方向，并在每年数次架构回顾时更新即可。

2. 推荐结构：鸟瞰图加 Code Map

2.1 鸟瞰图：先解释系统解决什么问题

开头用一小段文字说明用户、核心目标和主数据/控制流。不要从类、函数或框架细节开始。

用户提交任务
→ API 接收请求
→ 调度模块分配任务
→ Worker 执行
→ Repository 写入存储
→ UI 展示状态

2.2 Code Map：解释粗粒度模块及其关系

Code Map 是“国家地图”，不是每个省份的详图。列出核心目录、模块或类型，说明各自职责、关键入口和依赖方向；细节应下沉到模块 README、设计文档、接口文档或源码附近的注释。

检查目录结构是否支持这张地图：逻辑上相邻的功能，是否也在目录树中相邻？如果不是，文档暴露的往往是结构可发现性问题。

3. 写出长期成立的架构不变量

architectural invariant 是无论实现如何演化都必须成立的规则。它比“当前函数怎么写”更适合出现在高层架构文档中。

API → Service → Repository

Controller 只能依赖 Service。
Service 不能依赖 Controller。
Domain 层不能依赖数据库实现。
UI 层不能直接访问数据库。

若规则重要且可判定，应进一步由 dependency graph、lint 或 structural test 执行。这样 ARCHITECTURE.md 说明“为什么与什么”，自动化工具保证“始终如此”。[OpenAI Harness（整理版）](/en/original-notes/self_study_notes/harness/OpenAI Harness/整理版/OpenAI Harness（整理版）) 说明了这种文档—工具—治理的完整闭环。

4. 命名优先于固定链接

应写出重要文件、模块和类型的名字，例如“认证逻辑由 AuthService 负责”，并鼓励读者使用 symbol search。避免将文档绑定到 src/auth/service.ts#L42 这类路径和行号，因为移动文件、重构符号、切换分支都会使固定链接失效。

在 Obsidian 学习笔记内部，稳定的笔记级 wikilink 仍然适用；此原则针对的是代码实现位置的脆弱深链接。

5. 与 Agent-first 仓库的关系

Agent 需要像新加入的工程师一样快速建立系统心智模型。短而稳定的 ARCHITECTURE.md 与简短的 AGENTS.md 配合：前者讲系统地图，后者给出任务入口、必读资料和验证路径；更细的内容则进入结构化 docs/。相关的仓库布局和反馈回路见 [OpenAI Harness（整理版）](/en/original-notes/self_study_notes/harness/OpenAI Harness/整理版/OpenAI Harness（整理版）)。

[architecture_example（整理版）](/en/original-notes/self_study_notes/harness/OpenAI Harness/整理版/architecture_example（整理版）) 展示了 rust-analyzer 如何为 parser、syntax、hir、IDE、LSP server 等模块写出职责、边界和不变量，同时把测试、错误处理与 observability 作为横切关注点说明。

6. 可直接复用的模板

# Architecture

## Problem Overview

系统解决什么问题、服务谁，以及最重要的端到端流程。

## System Flow

User → API → Service → Repository → Database

## Code Map

### src/api

HTTP 接口层；解析请求并返回响应，不包含业务规则。

### src/services

业务逻辑层；协调领域规则与数据访问。

### src/repositories

数据访问层；封装数据库和外部存储。

## Dependency Rules

API → Service → Repository

Repository 不依赖 Service 或 API。

## Related Documents

- 认证设计：`docs/design/auth.md`
- 数据模型：`docs/generated/schema.md`

7. 审阅清单

首段能否让新读者说清系统服务谁、解决什么问题？
是否给出最重要的数据或控制流？
Code Map 是否只覆盖粗粒度、稳定模块？
依赖方向和 API Boundary 是否明确？
是否把实现细节、行号链接和易变内容下沉到其他文档？
是否有可自动执行的重要不变量？
是否能在每年数次架构回顾中低成本更新？

ARCHITECTURE.md：代码库导航地图